IsEqual used in all collections for object
identification
Compare if objects are put in sorted collections
(instances of class SortedObjList)
Hash if objects are put in collections based on hash
structures (instances of class Set)
Memory Management
The collection classes store only references (pointers) to
objects and not the objects themselves. Due to the possibility that an
object is contained in more than one collection, a collection cannot decide
when an object should be deleted. For this reason all collections use the
policy to manage only the storage for the collection data structures but
not for the objects stored in the collection. The decision when to delete
an object is up to the client of a collection. Deleting a collection does
not delete the managed objects. The method FreeAll can be used to
actually delete the collected objects. But take care that the deleted
objects are no longer referenced by other objects.
Collection Types
The subclasses of Collection implement different ways of storing and
accessing the objects. These different approaches result out of certain
trade-offs between needed functionality, flexibility and efficiency. The
inheritance relationship among the different classes is shown in the
following table:
Collection abstract superclass for all collection classes
Set hash table
IdSet hash table based on the address of an object
Dictionary data structure for storing key value pairs
IdDictionary same as above, but the address of an object
is used as key
ObjArray array of object pointers, with range checking
and dynamic grow and shrink
SeqCollection abstract superclass for collections
that preserve the order in which objects are added
ObjList doubly linked list
SortedObjList sorted list based on
Object::Compare()
OrdCollection Ordered Collection - array based implementation
of a list
Collection implements several methods to convert a collection to
another type: method AsBag AsSet AsObjArray AsObjList
AsOrderedCollection AsSortedObjList. The resulting collection of a
conversion may contain less objects than the original collection, e.g. if a
Bag is converted to a Set, multiple occurrences of an object
are lost.
Retrieval of Elements
Collection provides two different mechanisms for retrieval
of elements. The first involves a pointer comparison
between the search argument and the elements in the collection. This way of
comparing is often referred to as identity test.
The other way is based on the method @Object::IsEqual of the
searched argument. This way of comparing is often referred to as equality test.
This distinction is of central importance for collections because the method Object::IsEqual does not uniquely identify an object. The
duality of object identification is also reflected in the corresponding
methods for finding and accessing objects. Examples are method
Find FindPtr, method OccurrencesOf OccurrencesOfPtr and method Remove RemovePtr. Methods whose names end in ...Ptr use
pointer comparison, the others are based on the method
Object::IsEqual.
The elements of a sequenceable collection can additionally be accessed by
the method At. For example, foo->At(0) returns the first
entry, foo->At(1) the second, and so on. The last entry is numbered
one less than the value given by the method Size.
Iterators
Getting the objects of a collection one by one is done by a special object
called iterator. The order in which the objects are visited
depends on the type of the collection. Objects in a sequenceable collection
are visited in the order in which they have been added or sorted. Objects
of other collections are visited in an undefined order. The abstract
interface of all iterators is defined by the class Iterator.
Every collection provides an own iterator which is returned by the method MakeIterator (to reduce the memory overhead ET++ uses its own
memory management for iterators).
Since iterators are typically short living objects, the class
Iter provides an easy to use interface to them. This class takes care of
freeing a dynamically allocated iterator in its destructor (see example
below).
The method Iter::operator() returns the objects of the collection
one by one. Since the method returns an object of type Object* it
typically has to be casted to a more specific type before an operation can
be executed.
For security reasons Collection implements a mechanism called
Robust Iterators. If an object is removed from a collection
while an iterator is active, then the object is replaced by an instance of
the class DeletedObject. Iterators ignore "deleted objects".
These "place holders" are kept in the collection until the last iterator
has finished its work. See technote 'Robust Iterators' for more
details.
The following example shows how to use iterators:
{
OrdCollection *shapes;
VObject *current;
Iter next (shapes); // Create an iterator named 'next'
while (current = (VObject*)next()) // Get objects one by one and cast them
{
current->Draw(rect); // Use the 'current' VObject
}
} // End of block, the destructor of 'next' deletes the dynamically
allocated iterator
A method can be applied to all objects of a collection with the macro
ForEach:
Collection *col;
bool on;
col->ForEach(VObject,Enable)(on,redraw);
In this case col is a collection of VObjects and the method Enable is called for all its elements with the arguments on and redraw.
Enumerating Objects
Collection implements two methods which are similar to the
operations selection and projection of the set theory.
The method Select creates a subset of a collection. The method Collect creates a projection of a collection.
classes are always derived from Collection.
class Collection
is never reused directly.
class Collection is abstract.
class Collection contains 49 methods.
Collection
man2html: unable to open or read file ../mann/Collection::Add.n
man2html: unable to open or read file ../mann/Collection::AddAll.n
man2html: unable to open or read file ../mann/Collection::AddVector.n
man2html: unable to open or read file ../mann/Collection::AnnounceRemove.n
man2html: unable to open or read file ../mann/Collection::AnyDeleted.n
man2html: unable to open or read file ../mann/Collection::AsBag.n
man2html: unable to open or read file ../mann/Collection::AsObjArray.n
man2html: unable to open or read file ../mann/Collection::AsObjList.n
man2html: unable to open or read file ../mann/Collection::AsOrderedCollection.n
man2html: unable to open or read file ../mann/Collection::AsSet.n
man2html: unable to open or read file ../mann/Collection::AsSortedObjList.n
man2html: unable to open or read file ../mann/Collection::At.n
man2html: unable to open or read file ../mann/Collection::CheckActiveIter.n
man2html: unable to open or read file ../mann/Collection::CheckNotNull.n
man2html: unable to open or read file ../mann/Collection::Clone.n
man2html: unable to open or read file ../mann/Collection::Collect.n
man2html: unable to open or read file ../mann/Collection::Collection.n
man2html: unable to open or read file ../mann/Collection::Contains.n
man2html: unable to open or read file ../mann/Collection::ContainsPtr.n
man2html: unable to open or read file ../mann/Collection::Detect.n
man2html: unable to open or read file ../mann/Collection::DisplayOn.n
man2html: unable to open or read file ../mann/Collection::Empty.n
man2html: unable to open or read file ../mann/Collection::EnterIter.n
man2html: unable to open or read file ../mann/Collection::ExitIter.n
man2html: unable to open or read file ../mann/Collection::Find.n
man2html: unable to open or read file ../mann/Collection::FindPtr.n
man2html: unable to open or read file ../mann/Collection::FreeAll.n
man2html: unable to open or read file ../mann/Collection::GrowBy.n
man2html: unable to open or read file ../mann/Collection::Hash.n
man2html: unable to open or read file ../mann/Collection::InIterator.n
man2html: unable to open or read file ../mann/Collection::InspectorId.n
man2html: unable to open or read file ../mann/Collection::IsEmpty.n
man2html: unable to open or read file ../mann/Collection::IsEqual.n
man2html: unable to open or read file ../mann/Collection::MakeIterator.n
man2html: unable to open or read file ../mann/Collection::NullPointerWarning.n
man2html: unable to open or read file ../mann/Collection::OccurrencesOf.n
man2html: unable to open or read file ../mann/Collection::OccurrencesOfPtr.n
man2html: unable to open or read file ../mann/Collection::PrintOn.n
man2html: unable to open or read file ../mann/Collection::ReadFrom.n
man2html: unable to open or read file ../mann/Collection::Remove.n
man2html: unable to open or read file ../mann/Collection::RemoveAll.n
man2html: unable to open or read file ../mann/Collection::RemoveDeleted.n
man2html: unable to open or read file ../mann/Collection::RemovePtr.n
man2html: unable to open or read file ../mann/Collection::Select.n
man2html: unable to open or read file ../mann/Collection::Size.n
man2html: unable to open or read file ../mann/Collection::assertclass.n
man2html: unable to open or read file ../mann/Collection::setCurrentCollection.n
man2html: unable to open or read file ../mann/Collection::~Collection.n